Inside Macintosh: QuickDraw GX Graphics /

Chapter 2 - Geometric Shapes / Geometric Shapes Reference

Functions / Creating Geometric Shapes

GXNewPolygons

You can use the GXNewPolygons function to create a new polygon shape and initialize its geometry.

gxShape GXNewPolygons(const gxPolygons *data);

data

A pointer to the initial polygon geometry.

function result

A reference to the new polygon shape.

DESCRIPTION

The GXNewPolygons function creates a copy of the default polygon shape, sets the owner count of the copy to 1, initializes its geometry with the values in the data parameter, and returns a reference to it as the function result. If you specify nil for the data parameter, this function returns a polygon shape with no polygon contours.

Although this function creates a copy of the default polygon shape, it does not create a copy of the default polygon's style, ink, or transform objects. The new polygon shape returned by this function contains references to same style, ink, and transform as the default polygon shape.

Implementation Note

In version 1.0 of QuickDraw GX, the total size of a polygon geometry may not exceed 2,147,483,647 bytes. If the size of the data you provide in the data parameter exceeds this limit, the GXNewPolygons function posts a size_of_polygon_exceeds_implementation_limit error.

SPECIAL CONSIDERATIONS

If no error occurs, the GXNewPolygons function creates a shape; you are responsible for disposing of this shape when you no longer need it. See Inside Macintosh: QuickDraw GX Objects for information about creating and disposing of shapes.

If an error occurs, this function returns nil as the function result.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
number_of_points_exceeds_implementation_limit
number_of_contours_exceeds_implementation_limit
size_of_polygon_exceeds_implementation_limit
count_is_less_than_one	(debugging version)

SEE ALSO

For an example that uses this function, see "Creating and Drawing Polygons" beginning on page 2-45.

For a discussion of polygons and the default polygon shape, see "Polygon Shapes" beginning on page 2-22.

For a description of the gxPolygons structure, see page 2-106.

To create a new polygon shape without specifying an initial geometry, see the description of the GXNewShape function in the chapter "Shape Objects" in Inside Macintosh: QuickDraw GX Objects.

To set the geometry of an existing polygon shape, see the description of the GXSetPolygons function on page 2-131.

To draw a polygon geometry without creating a polygon shape, see the description of GXDrawPolygons on page 2-161. To draw a polygon shape, see the description of GXDrawShape in the chapter "Shape Objects" in Inside Macintosh: QuickDraw GX Objects.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help